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Abstract 

Because of their narrow width, r decays can be weh separated from their production process. 
Only spin degrees of freedom connect these two parts of the physics process of interest for high 
energy cohision experiments. In the fohowing, we present a Monte Carlo algorithm which 
is based on that property. The interface supplements events generated by other programs, 
with r decays. Effects of spin, genuine weak corrections or of new physics may be taken into 
account at the time when a r decay is generated and written into an event record. 
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1 Introduction 



Before we will present our C++ Interface of TAUOLA, for LHC era generators, let us first 
list projects and applications which helped us to gain experience and to define the main tasks 
our interface for a r decay generator has to resolve. 

In the present day experiments at High Energy Physics accelerators, interpretation of re- 
sults becomes increasingly involved. Not only the detector response is complex, but some 
theoretical effects need to be removed. Otherwise results are difficult to interpret for the 
non-specialist. For that purpose the concept of work with realistic and idealized observables 
was introduced as well as finally with pseudo-observables which can be easily understood 
by theorists, such as W, Z masses or couplings. Good examples of such approaches were 
measurements of the two-fermion final states at LEP. Because of increasing precision of the 
experimental measurements, definitions of quantities to be measured, simple at first, later 
evolved into several options [1], each based on the properties of individual detectors and each 
requiring individual discussion of the systematic error. One could assume, that if all theo- 
retical effects are embodied into one theoretical black-box and, experiments while using it 
tune parameters (representing pseudo-observables) to the data, interpretation of the observed 
effects could be separated into theoretical and experimental components. Unfortunately this 
strategy is limited, as it leaves little room for cases where theory and experimental effects are 
convoluted: size and even nature of the theoretical corrections depend on the experimental 
conditions. Such discussion on observables involving r decays can be found in [2j. Recently, 
discussion for the physics of r production and decay at low energies where similar aspects 
are addressed, was presented in [3j. 

For LHC experiments r decays are not of primary interest in themselves, but rather will be 
used to measure properties of r production processes. Let us explain this using examples. 
Physics effects necessary for the prediction of hard processes at the LHC experiments can be 
separated into several parts, among them: parton showers, the underlying event and struc- 
ture functions, final state QED bremsstrahlung, QED bremsstrahlung interference between 
initial and final states and finally the hard process including electroweak corrections. Such 
separation is not only for the convenience of organizing theoretical work but provides efficient 
and flexible component in the framework for experimental data analysis strategy (see eg. ^ ) . 
Some of such building blocks are of genuine theoretical interests, some others are not so much. 
The hard process usually depends on the parameters intended for the measurement, eg. W 
or Higgs mass, or new coupling constants. Other building blocks may be less interesting, 
nonetheless they may affect the results of measurements. This is certainly true in the case of 
the underlying event or missing transverse energy or px distributions generated from parton 
showers [2]. It may also be the case for QED final state bremsstrahlung or initial- final state 
interference (where potential difficulties may be expected [5j and predictions may need to be 
fixed with the help of experimental data). 

The black-box approach, where all simulation segments are put together by theorists, may 
look advantageous to the experimental user. However in such a case one has less flexibility 
to distinguish experimental effect from the theoretical ones, thus limiting control on the 
systematic errors. The particular problems may be left unnoticed. Typically the difficulties 
will not affect all observables. Unfortunately, complications tend to show up only when more 
detailed discussion on the systematic errors of experimental analysis is performed. 

In the present document we discuss the implementation of r decays into a simulation chain as 
a separate module which can be configured by the end user. For the purpose of generation of 
T decays themselves, the TAUOLA library, as described in [6l 13 [8] is used. This part of the code 
is expected to be a black-box for the High Energy experimental user. At present, from the 
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technical side, the black-box consists of the same FORTRAN code as described in [9j. We will 
call it TAUOLA FORTRAN. Such organization makes it easy for low energy phenomenologists 
or experimentalists to work on this part of the code, such as the activities described in [3], 
leading to the new parametrization of hadronic r decay currents becoming available for High 
Energy experimental users in a rather straightforward way. 

The role of the interface is to prepare information on the r (four-momentum, spin state) in 
a format which is understood by TAUOLA FORTRAN, and as a post processing step to return 
(insert) r decay products to the primary event record. Finally, role of such interfacing code 
is to calculate dedicated weights from the production process information as well as from 
the decay, and unweight accordingly to standard MC procedures. Spin effects, electroweak 
corrections and also effects of anomalous couplings can be introduced in this way. 

A rather modest version of TAUOLA Universal Interface based on FORTRAN HEPEVT event 
record is described in [9], we will call it TAUOLA Fortran Interface. A new version of 
TAUOLA Universal Interface based on HepMC |10] . the most popular event record of C++, 
will be documented here. It also includes new functionalities. We will call it TAUOLA C++ 
Universal Interface, or, if no ambiguity could arise simply TAUOLA C++ Interface or 
just TAUOLA Interface if it is clear that the C++ not the FORTRAN version is in mincj^- 
The PHOTOS generator for QED bremsstrahlung in decays, which was previously distributed 
together with TAUOLA FORTRAN, is not discussed in the present papeiG. It is now embodied 
in a separate module [IH [T^ of the Monte Carlo simulation chain, as the PHOTOS generator 
has found significant applications outside the domain of r decays. That is why, in the future, 
we plan to distribute the C++ version of PHOTOS separately [15] . 

Important physics improvements, with respect to the TAUOLA FORTRAN Interface implemen- 
tation, described in [9], comes with the code presented here. In particular, transverse spin 
correlations have been implemented for processes mediated by Zj'^* and genuine electroweak 
corrections are now available for such processes. With the new interface, it is rather straight- 
forward to implement effects beyond standard model physics. Only read-in data-tables should 
be replaced, no modification to the code itself is needed. Further minor extensions include an 
algorithm to decay a single r with a user defined polarization, or the availability of methods 
to access generated r leptons helicity states. 



For a T decay to be generated it is enough to know its spin state and define the frame in 
which the decay should be performed. In case there are more than one r lepton in the final 
state, the quantum spin state of both (or more) r leptons must be provided in the form of 
a density matrix. The exact algorithm for the generation of spin correlations exist since the 
papers [QITIIH]- However, for the algorithm functioning, the density matrix must be known 
exactly as well. 

In practice, the actual form of the spin density matrix (in our present paper it will be called 

^The main class of TAUOLA C++ Universal Interface is called Tauola. 

^PHOTOS was distributed together with TAUOLA since ref. [S]. That is why it is present in our TAUOLA 
FORTRAN but will be not used here. 
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Requirements for TAUOLA Interface 



2.1 



General Requirements 
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Rij, exactly as in the original TAUOLA FORTRAN and its documentation) is often available with 
some approximations only. With the increasing precision of experiments, one may need to 
remove certain approximations introduced into Rij. Already now, our program features, as an 
option, complete spin effects in decays of r pairs originating from the annihilation of quarks. 
Effects of genuine weak corrections are included, and an extension for the implementation of 
new physics signatures is straightforward. 

One should not forget that the density matrix itself is not the only place approximations 
occur. Effects of higher order QCD corrections need to be taken into account to define the 
kinematical configuration of initial partons used in spin density calculations (otherwise the 
density matrix for each individual process would have to be provided). At present, this is 
available in the leading (collinear) approximation only. 

Before we will discuss details of specific implementation, let us recall first, the minimal list 
of steps the interface has to perform, independent of the programming language and data 
structure used. 

1. The r lepton or lepton pair(s) have to be localized in the event record. For processes 
mediated by W bosons (or charged Higgs) Uj- has to be localized as well. 

2. If possible, the hard process leading to r production has to be determined. This is 
necessary to control transverse spin correlations. Preferably minimal information from 
the host generators should be used. This is to reduce dependence on the host prograrrH. 

3. Flavours and orientation of fields entering the production vertex for intermediate states, 
such as Z/j*, have to be reconstructed too. This orientation (with respect to rest- 
frames) is necessary for calculation of the spin density matrix, if spin of intermediate 
state is different from zero. 

4. The relative orientation of and r~ rest-frames should be established and respected 
by Lorentz transformations. 

5. Transformation of r decay products from the r rest-frame to lab frame has to be 
performed and the event record has to be completed with r decay products. 



2.2 C++ Specific Requirements 

The C-|--|- version of the TAUOLA Interface implements all functionalities of its predecessor, 
the TAUOLA Interface coded in FORTRAN [9J. It can be attached to any Monte-Carlo 
program where r's are generated, provided its output is available through a HepMC [10] event 
record. 

This condition is not very restrictive, is seems that HepMC will remain a generally accepted 
standard for the near future. However, already now several different options for how HepMC 
is used are widespread. Possibility of the flexible adaptation of our event record interface 
to different options has been considered in the design, drawing experience from MC-TESTER 
[m [IS]. We have also envisaged the possibility that HepMC may one day be replaced by 
another standard of event record, and we have provided an easy way to extend the interface 
to a possible new event record standard. 

^We target also applications when event records will be filled by measured data. For example, measured 
fj.'^ IJ,~ events can be modified and final state muons replaced appropriately with t'^t~ pairs. Then generation 
of r lepton decay is necessary. 
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2.3 Object Oriented Event Records - The Case of HepMC 



In adopting TAUOLA Interface to the C++ event record format the difference between the 
HEPEVT event record used in the FORTRAN version of TAUOLA Interface and HepMC event 
record which is used for the C++ based interface has to be taken into account. In the first 
case the whole event was represented by a common block containing a list of particles with 
their properties and with integer variables denoting pointers to their origins and descendants. 
The HepMC event structure is built from vertices, each of them having pointers to their origins 
and descendants. Links between vertices represent particles or fields. In both, FORTRAN and 
C++ cases, the event is structured as a trefQ, the necessary algorithms are analogous, but 
nonetheless different. 

In HepMC version 2.04, an event is represented by a GenEvent object, which contains all 
information regarding itself, including event id, units used for dimensional quantities in the 
event and the list of produced particles. The particles themselves are grouped into GenVertex 
objects allowing access to mother and daughter particles of a single decay. Vertices provide 
an easy way to point to the whole branch in a decay tree that needs to be accessed, modified 
or deleted if needed. The information of a particle itself is stored in a GenParticle object 
containing the particle id, status and momentum as well as information needed to locate 
its position in the decay tree. This approach allows traversing the event record structure in 
several different ways. 

The HepMC event record format is evolving with time, making it necessary to adapt the code 
to the new versions. HepMC version 2.05 is used as a reference. In the case of version 2.03 
restrictions on methods for units conversion have to be taken into account, for details see 
Appendix IB.5i One should keep in mind that future adaptations to HepMC changes may 
restrain backward compatibility. 

Evolution of the HepMC format itself is not a crucial problem. In contrary, conventions how 
physics information is filled into HepMC represent the source of main technical and also physics 
challenge for our interface. This is quite similar to the previous HEPEVT - FORTRAN case. Let 
us discuss this point in more detail now. 

2.3.1 Event Record Structure Scenarios 

While many Monte-Carlo generators (eg. PYTHIA 8.1 [,16j, HERWIG++ ^7\) store events in 
HepMC format, the representations of these events are not subject to strict standards, which 
can therefore vary between Monte-Carlo generators or even physics processes. Some examples 
of these variations include the conventions of status codes, the way documentary information 
on the event is added, the direction of pointers at a vertex and the conservation (or lack of 
conservation) of energy-momentum at a vertex. Below is a list of scenarios we have observed 
in Monte-Carlo generators used for testing the code. 

This list will serve as a declaration for convention of HepMC filling, which the interface should 
be able to interpret correctly. 

• 4-momentum conservation is assumed for all vertices in the event record. 

• Status codes: only information whether given particle is incoming, outgoing or inter- 
mediate will be used, 

''At least in principle, because in practice its properties may be rather of the graph of not universally 
defined properties. This makes our task challenging. 
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• Pointers at a vertex are assumed to be bi-directional. That is, it is possible to 
traverse the record structure from mother to daughter and from daughter to mother 
along the same path. 

Extensions/Exceptions to this specifications are handled in some cases. We will call them 
options for conventions of event record filling. 

• Vertices like — t- and — t- t^7 where 4-momentum conservation is not preserved, 
but this non-conservation is balanced, for example, between the two branches outgoing 
from Z . 

• Lines representing intermediate bosons may be missing. In fact this may be unavoid- 
able, if several diagrams contribute simultaneously. In that case, our algorithm makes 
a choice based on an approximation that only the dominant single diagram is consid- 
ered and an intermediate boson state is defined accordingly on the fly. Other possible 
treatments: statistical choice of the dominant process, or calculations based on higher 
order matrix elements for the hard process, are not available at present. 

• As in the FORTRAN cases, we expect that new types of conventions for filling the 
event record will appear, because of physics motivated requirements. Unfortunately, 
the resulting options do not always guarantee an algebraically closed structure. Host 
program specific patches may need to be defined for the TAUOLA interface. Debugging 
it could be time consuming, and will need to be repeated for every new case. 

Detailed conventions for the actual filling of physics information into HepMC format is defined 
by authors of each Monte Carlo program. In future, an important special case of event 
records filling with information extracted from experimentally observed event (eg. Z — )• /x"*"/!" 
modified later to Z — )• r+r^) should be allowed. Obviously, a new type (or types) of HepMC 
filling will then appear. 



3 Design 

The structure of our code is documented using Doxygen standards [18j and is presently 
available from the project web page [19]. The source code for this web page is also available in 
our package distribution. Doxygen documentation can be thus compiled on a users platform, 
and hence provide documentation which matches the actual version of the distribution. 

Let us present here briefly the directory structure and list the main classes with a short 
description of their functionality. 



3.1 Interface Structure and Responsibilities 

The choice of splitting the source code into three main modules, see Fig. 13.11 (blue part), 
allows to separate the FORTRAN related code from the abstract C++ interface and the 
concrete implementation of the interface created for the appropriate event record. 

• Tauola Fortran Interface 

This part of the code provides an interface to the FORTRAN library of TAUDLA. In 
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Figure 1: TAUOLA C++ Interface class relation diagram 



particular, routines necessary for library initialization and wrapper for routine invoking 
the decay of a single r. Parts of the interface code are still left in FORTRAN, but can 
be rather easily rewritten to C++. The most important method, f ilhep_, is already 
implemented in C++. Its FORTRAN predecessor writes single particles to the HEPEVT 
common block. At present the method f ilhep_ inserts the particle into the HepMC event 
record but remains to be called from the FORTRAN library. For further details see 
Appendix [Al 

• Tauola C-\ — \- Interface 

The abstract part of the interface to the event record. The class TauolaEvent contains 
information regarding the whole event structure, while TauolaParticle stores all in- 
formation regarding a single particle. All particles used by the interface are located in 
the event in the form of a list of TauolaParticle objects. The last class located here, 
TauolaParticlePair, is the core of all polarization and decay algorithms. They are 
independent from the event record used by the interface as they operate on these two 
abstract classes presented above. 

• Event Record Interface 

The event record implementation classes. All classes stored here represent the imple- 
mentation of specific event record interfaces and are responsible for reading, traversing 
and writing to the event record structure. Only TauolaEvent and TauolaParticle 
classes must be implemented. The HepMC event record interface is implemented through 
TauolaHepMCEvent and TauolaHepMCParticle. 
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Directory Structure 

src/eventRecordlnterfaces/ - source code for classes which interface with HepMC. 
Classes: 

— TauolaHepMC Event - Interface to HepMC: iGenEvent objects. 

— TauolaHepMCParticle - Interface to HepMC ::GenParticle objects. 

src/tauolaCInterfaces/ - source code for general TAUOLA Interface classes, such 
as those responsible for spin correlations and boosting. 

Classes: 

— DecayList - Storage class for keeping track of TauolaParticlcs and their indices 

— Tauola - Controls the configuration and initialization of TAUOLA FORTRAN. 

— TauolaEvent - Abstract base class for event information. 

— TauolaParticle - Abstract base class for particles in the event. This class also 
handles particle boosting. 

— TauolaParticlePair - Contains two objects of type TauolaParticle that are re- 
lated by the same mother. Spin correlations and other minor algorithms are han- 
dled here. 

src/tauolaFortranlnterfaces/ - interface to TAUOLA FORTRAN routines and common 

blocks. 

Files: 

— f_Decay - contains a wrapper for the TAUOLA FORTRAN routine for decaying r's 
(DEKAY). 

— f_FilHep - provides a method which TAUOLA FORTRAN calls to fill a r decay 
product into the event record. 

— fJnit - contains a wrapper for the TAUOLA FORTRAN routines for tauola initial- 
ization. 

— f_ Variables - contains definitions of TAUOLA FORTRAN routines and common 
blocks used by other methods in tauolaFortranlnterfaces. 

— tauola_extras.f - contains extra FORTRAN routines (taken from the TAUOLA 
Interface in FORTRAN) which should ultimately be migrated to C-|— 1-. 

src/utilities/ - source code for utilities that help in debugging and plotting distribu- 
tions. 
Classes: 

— Log - General purpose logging class that allows filtering OTit output messages of 
TAUOLA C++ Interface and keeps statistics regarding tauola run. 

— Plot - Simple class that gathers data for some useful debug plots, 
examples/ - examples of different TAUOLA C++ Interface uses 

— taumain_stand_alone_example - stand alone example with a simple e'^e" — >■ 
T'^T^ event in HepMC format and then r's decayed by TAUOLA. 

— single_tau_gun_example - example of TAUOLA linked with pythia 8.1 and used 
to decay single r selected from the event record. 

— taumain_pythia_example - example of TAUOLA linked with pythia 8.1, and 
decay chain analysed with MC-TESTER. 

SANC/ - code for the computation of electroweak corrections. 
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• include/ - directory for the header files. 

• lib/ - directory for the compiled libraries. 

• documentation/ - contains doxygen documentation and this latex file. 

• tauola-fortran/ standard TAUOLA FORTRAN distribution exactly as described in P5] . It 
is kept intact and is prepared for future updates, see ref. |3j for details of that project. 



3.3 Algorithm Outline 

An overview of the algorithm for the TAUOLA Universal Interface is given below, for more 
detail the reader should refer to the project's Doxygen documentation [19]. Documentation of 
the TAUOLA FORTRAN Interface [9j describes some aspects of the spin correlation algorithm 
which are also relevant to this interface. 

The first step is creation of a TauolaHepMCEvent object from a HepMC: :GenEvent event 
record. At this step the units for dimensional quantities (four-momenta, masses, etc.) are 
checked, and if needed the HepMC event record is reset to use GEV and MM ensuring proper 
execution of r decay library. After a TauolaHepMCEvent is created the decayTausO method 
should be executed by the user's cod^, invoking the following process: 



1. The HepMC event record is traversed and a list of all stable r's in the event is created. 

2. From each found r location, the tree is traversed backwards so that information about 
the production process can be extracted and used for the calculation of the spin density 
matrix. 

3. The siblings of the r are identified through common parents, i.e. requiring that they 
are produced at the same HepMC vertex. In cases such as r — t- 7r, the parent(s) are 
defined as the particle(s) which produced the first r; r and Ur siblings are paired to the 
r. 

4. The density matrix is set-up using information about the r-pair and their parent type 
(for Z/7 processes, grandparent information is also required). This is described in detail 
in Sec. HI The density matrix assumes a center-of-mass frame for the r-pair, with the 



r's and their grandparents orientated as shown in Figure 2(a 



5. The pair is then decayed by executing the DEKAY routine for each r in the pair. The 
DEKAY routine is stored in the tauola-fortran directory, for details see Appendix lA. 21 

6. A spin weight is calculated using the polarimetric vectors returned from TAUOLA FORTRAN 
and the density matrix previously set-up (described in Sec. H]). 

7. If the decays are rejected, the pair is decayed anew and the process is repeated until 
the decays are accepted. In this way unweighting of spin effects is performed. 

8. Once accepted, the decay products are added into the event record with the procedure 
as follows: 



(a) As the density matrix is only valid in the special reference frame of Figure 2(a) 
the r-pair are boosted and rotated into this hard process frame. 



^Prior to this step the user may want to execute Tauola: :decayOne(. . .) for r leptons, where TAUOLA 
Universal Interface is expected not to work properly. For details see Appendix [Cj 
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(b) The DEKAY routme of TAUOLA FORTRAN is executed with state = 11 or 12 (write). 
This initiates TAUOLA FORTRAN to return the daughter information via the f ilhep_ 
routine (see Section [A.2|l . 

(c) The r's status code is changed from "1" (stable particle) to "2" (intermediate 
particle) . 

(d) A new object HepMC::GenParticle is created for each daughter and the appropri- 
ate tree structure is created and added into the event. 

(e) Each daughter is boosted using the r's 4-momentum (as TAUOLA constructs a decay 
for a r at rest) to the hard process frame. 

(f) The r's and their decay products are boosted back into the laboratory frame. 

9. As the final step, the position of vertices containing the r's and their decay products is 
set according to the r's momentum and lifetime. 

The underlying HepMC::GenEvent is hence modified with insertion of r decay products. 
All that remains is to convert the event back to its initial units, which is done via the 
eventEndgame ( ) routine of the TauolaHepMCEvent class. 



If more than one r lepton is present in a final state, then not only is the individual spin state 
for each r necessary for proper generation, but the complete correlation matrix of all r leptons 
must be taken into account as well. In the case of r-pair production, the standard algorithm 
explained in [6l [8] can be used without much modification. For the single r produced in a 
r, pair, it is convenient to use the same algorithm as well, even though it is not necessary 
from the physics point of view. 

Let us describe now the algorithm given in Refs. We will use definitions and notations 

from that papers as well. Spin correlations and spin polarization effects can be simulated by 
accepting or rejecting a pair of generated r decays based on a weighting factor wt. 



where and h? are the polarimetric vectors for the r+ and r respectively and Rij is the 
density matrix associated with the r production vertex. The matrix Rij depends on the 



on the respective decays of r+ and r . The solution can be used for r — Ur production as well. 
In this case Vr decay is not performed and its polarimetric vector is set to h = (2,0,0,0). 

A pair of r decays should be accepted if the weight is greater than a randomly generated 
number between and 1. If this condition fails, the r pair decays should either be rejected 
and regenerated, or rotatecH, and the weight recalculated. The production process does not 
need to be reprocessed. 

^Rotation instead of rejection increases efficiency by a factor of 4. This however only affects the generation 
of r lepton decays and represents a small fraction of the total time of constructing the event. 



4 Calculation of Spin Correlations 





jj=0 
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The density matrices, Rij, for the most standard processes of r-pair production, are docu- 
mented below. The following frame conventior|l| was adopted: 

• The r-pair's center of mass system is used 

• The r"*" (if present) lies along the positive z axis 

• The T~ (if present) lies along the negative z axis 

• The incoming beams (if present) lie in the z-y plane. 

• If applicable, the incoming antiquark (or antilepton) y momentum component is posi- 
tive. 

h is defined such that hQ=l and /ii,2,3 form the polarimetric vertex returned from TAUOLA 
FORTRAN (see DEKAY in Appendix IA.2p . The h is defined in the rest frame of the r it was 
calculated for. One should stress that formally speaking Rij does not represent a Lorentz 
invariant object. Its first index is defined in the rest frame of the r"*", whereas the second 
index is in the frame of the t~. 

In the following subsections we will list the form of Rij for the most commonly used processes 
of r-pair (or r, u) production. 



4.1 Form of Rij for Standard Processes 



4.1.1 Z/7 ^ T+r- 



R 



1 2P^{cose) - l\ 





^2^^(0056*) - 1 1 / 



where Pz is calculated from the square of the matrix elements of the Born-level 2 — )• 2 process 
//^ r+r". 

d(T(s,e,+,+) 



Pz{s,9) 



dn 



da{s,e, + ,+) dcr{s,e,-,-) 

dfl + dn 



9 is the angle between the incoming antiparticle beam and outgoing r^. If the incoming 
beam cannot be reconstructed from the event record the average of Pz should be used (which 
is equal to Pz{cos9 = 0)). The denotes that the spin states of r"*^ and r~ are parallel to 
the T"*" momentum. For "— " it is placed in the opposite direction. 

The spin correlation matrix explained above is approximate and is valid only for longitudinal 
spin effects. The object iJjj is nonetheless prepared to host complete spin effects. For that 
purpose information available from the module based on SANC can be used, see Appendix [Dl 
Further advantage is that genuine weak effects can be calculated and included as a weighl|f| 
not only on polarization but on the cross section as well. This was found to be numerically 



^ Fig. [2(a)] illustrates our choice too. There however the reaction frame is rotated by angle 9 around x axis. 

*In a similar way one can implement effects of new physics, such as Z' into the program. With the help 
of our interface effects of weak corrections on the cross section, and not only on polarization can be installed 
with additional weights. 
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important [2U[ [21] for final states of virtuality largely surpassing the Z mass and should be 
taken into account prior to the implementation of new physics effects. 

In the formulas above, the hard process kinematical variables s and Q have to be known for 
each event. Those variables, together with the flavour of the incoming beam are used by a 
module for calculating electroweak corrections or the function P^lfl 

To apply the method we need to identify the four momenta of the r"*" and r~ pair first. In the 
rest frame of the pair the two effective partons leading to the hard process are not necessarily 
back to back. Two scattering angles Q\ and Q2 can be thus reconstructed. The angle d\ is 
between the r"*" and the first incoming state, Q2 is between r~ and the second onqij. Both 
angles are calculated in the rest frame of the r pair. The average angle Q* accordingly to the 
description given in [S] is taken: cos0* = ''"^^ s-nKsinS'"'^' " 

If events originate from generator such as PYTHIA, the flavour of incoming partons is explicitly 
given or it can be calculated using information encoded in the event record. In the generic case 
this information is not available, and one will have to rely on measured structure functions 
and statistical choice. This is the method, for example, to be applied in the analysis where 
one reconstructs from experimental data decays Z — )• [i^ \i~ (or W — )• [xv^ and then replaces 
by the Monte Carlo generated r object. The resulting uncertainty on one hand will not 
be large; angular polarization dependence of d and u quarks couplings to a Z is not that 
different. On the other hand, a mismatch between choosing quark and antiquark may have 
larger effect. 

The density matrix presented above features only longitudinal spin correlations. Once the 
matrix K is replaced with the one featuring complete spin effects, see Appendix [Dl this is 
passed to the results of simulation as well, without any need of further changes. 

4.1.2 ^ r+r- and t+t- and mixed A°/H° t+t~ 

The complete density matrix for a scalar neutral Higgs boson is rather simple, 



R = 



n 













1 














1 





Vo 








-y 



it is also true for a pseudoscalar neutral Higgs boson 



R = 



(I 













-1 














-1 













-1/ 



^ The principle behind our solution, is quite similar to the one used in PHOTOS Monte Carlo where it is 
was shown [22] to be valid up to NLO (QED) precision level. It relies on factorization properties of fully 
differential distributions into the appropriately chosen Born level ones and emission factors. To achieve such 
precision in the case of spin correlations in proton-proton collisions, rather challenging work on QCD matrix 
elements would be necessary. At present, our predictions will not be better than LL on spin effects. It is 
known 23 , that the solution can not be constructed beyond NLO. 
^°We choose the first incoming state to be antiparticle. 
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A mixed /H^ — J- r+r represents only a slightly more complicated case: 



R 



/I 



Vo 





{ficosij))^ —siruj)'^ 
2l3cos(psin4> 









2(5cos(f>sinij> g 

{$cos(p) —sinif)^ g 
(l3cos(t>)'^+sin<f>'^ 







1/ 



where /3 = ^/l — {jr^ — )^ ^-nd </> is the scalar-pseudoscalar mixing angle. 



AO/hO 



4.1.3 VF=^^T=^z^ 



For W the matrix takes the following form: 



R 



/I 1\ 





\i oy 



4.1.4 H^-^T^u 



For charged Higgs decay the matrix Rij differs from the W case by signs only: 



R 



(I -1\ 





\-l / 



4.2 Cases of Partly defined Hard Processes 

4.2.1 r+T Pair with Multiple Parents and Sisters 

If a r^T~ pair is found with multiple parents rather than a single parent, the parent type 
is assumed to be a Z/7 with the 4-momentum reconstructed from the 4-momentum of the 
T pair. The density matrix 14.1.11 is used. For more details on the construction of effective 
incoming beams see Section 14.41 

4.2.2 tvt Pair with Multiple Parents and Sisters 

li a, T^v pair is found with multiple parents rather than a single parent, the parent type is 
assumed to be a with the 4-momentum reconstructed from the 4-momentum of the r Vj- 
pair. The density matrix [4.1.31 is used. 



4.2.3 Single r and Multiple Unpaired r's 

By default a single r, with no r or pairing, is treated as unpolarized and spin effects are 
ignored. However, in such a case the TAUOLA decayOne method, see Appendix IC. 81 can be 
used if including spin effects is requested. This method can be applied by the user, in such a 
case the spin state of a single r can be imposed. The method can be used even for multiple 
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r final state and exact spin correlations. In those cases a user defined quantization frame 
for each r may be necessary. For each r a distinct routine for boosting from its rest-frame 
to the lab-frame may be necessary. The appropriate method is explained in the Appendix 
mentioned above. 

Another user defined option (which may become in the future a default part of the TAUDLA 
Interface) is when pairing can not be done on the basis of inspecting r mother (s) but can be 
performed according to the closeness of the reconstructed invariant masses of the pairs to the 
masses of W's or Z's (if the appropriate Standard Model processes are under considerations). 
In general, as such configurations will often appear for processes of new physics, again a user 
defined and hard process dependent solutions based on the TAUOLA decayOne method, might 
be the only option. 



4.3 Quantum Entanglement and Helicity States 

One of the convenient feature of Monte Carlo simulation is the availability of variables used 
in the generation of hard processes. However, it is often not possible to define in an exact 
manner what is the energy transfer, eg. in the Z propagator, if several diagrams contribute 
simultaneously. Nonetheless use of such information is tempting as it would be helpful to 
validate algorithms used in experimental analysis for defining observables aimed at the mea- 
surement of the Z lineshape. 

Another example of such useful variables are the helicities of r"*" and t~ . Even though, it 
is possible to attribute such variables only in the ultrarelativistic limit and its use can be 
restricted to a downgraded physics approximation only (quantum entanglement [25] ignored), 
helicity was offering invaluable help at LEP time, for the measurement of r polarization [26j. 

Our program provides helicity states of and t~ even in cases when exact spin effects are 
taken into account in the generation, as is the case of processes mediated by intermediate Z/'j* 
state or in Higgs boson decay. We just attribute helicity states for the r lepton after decays 
are already generated and accepted. The approximation used in calculation of these helicities 
is explained in Section 14.51 and technical aspects of our solution are given in Appendix IC.7I 
This information can be used for solutions similar to the ones in [26], but this time for LHC 
purposes 

4.4 Handling of Events with Bremsstrahlung or Parton Shower 
Activity 

Obviously, there are cases, when spin correlations calculated from Born level processes can 
not be applied directly. Good examples are: (a) Z — )• r+T^7, (b) /I + /2 — )• Z + X, 
Z — )• T^T~ where the intermediate state Z is explicitly stored, (c) /I + /2 — )■ t'^t^X or 
/I + /2 —7- t'^i't-X where the Z state is not available. Here X represents parton shower 
and/or final state bremsstrahlung. The fist step, necessary eg. for calculation of the spin 
correlation matrix, is to reconstruct effective Born level variables s and 9 and the incoming 
state fiavors; the arguments of the function Pz- This is equivalent to the construction of 
effective incoming and outgoing r fields. Let us discuss now our cases: 

a) An additional photon is added to the r with which it forms smaller virtuality. For 
construction of the transformation between the laboratory frame and rest frame of 
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r's the effective state Z — 7 frame is used instead of intermediate Z. This choice is 
motivated by inspection of properties of spin amphtudes. In such a frame the effective 
incoming states fl f2 wih not necessarily be back to back. The average of the two 
directions (0*, d' as explained earlier in this subsection) can be used. The virtuality of 
the Z is nonetheless used in the effective Born calculation. 

b) Additional fields X representing parton showers should be subtracted from /I or /2, 
preferably from the one with which it forms smaller virtuality. This is motivated by 
inspection of the spin amplitudes. Once the effective incoming states are constructed, 
the definition of boosting routines is straightforward. 

c) This case is a combination of the above two. Additional fields should be subtracted 
from fl f2 or considered as originating from the intermediate Z reconstructed on flight 
together with r^, r~. The minimalization of virtuality should be used as a guide 
whenever combinatorial choice has to be made. However electromagnetic charge or 
colour charge should not be neglected. Obviously photons should not be combined 
with neutrinos nor gluons with leptons. 

The approach presented above is explained in ref [5] in more detail. The principle is based 
on the simplest factorization properties of SM/QCD matrix elements. In particular the 
assumption is made that photon(s) can be treated as (nearly) collinear with one of the final 
state r leptons. Then the kinematics can be built on the r+r^ pair rest frame and the 
effective incoming states. The z axis is taken along effective antiparticle incoming state and 
y axis is of half plane including r~. The second effective beam is placed then in zy plane 
as well, even though it is not back to back with the first one. For calculation of Rij the 
variable s should be calculated from effective incoming states. The scattering angle can be 
calculated in the Z frame using formula for or 0*, see ref. [23]. In the collinear limit for 
photon emissions, Lorentz transformation between the r"*", r~ and Z rest frames is reduced 
to a simple boost along the r+ — r~ flight directions in the Z rest-frame. 

Further improvements with respect to that description require explicit use of higher order ma- 
trix elements. The described approximation is already quite good and works up to aQED/T^ — 
0.1 - 0.2 % precision level, for observables where it is not requested explicitly that high pT 
photons are present. 

Situation with initial state parton shower emissions is similar, however in this case the omitted 
terms for R calculation may be of the order of olqcdI't^- Thus significantly larger, but still 
at the level of ten percent or so. 

If the event record under study is originating from experimental data, the flavours of the 
incoming partons can not be known from the event record itself. Instead, information in 
PDFs can be used to attribute such flavours on a statistical basis and then used in the 
calculation of the matrix 



4.5 Exact Spin Effects and Helicity States 

Earlier in this Section we have listed some examples of spin polarization, spin correlation and 
density matrices. Those matrices can be easily changed/replaced by the externally calculated 
ones for the sake of studies on new physics phenomena, like a consequence of certain types 
of spin correlations on the signal/background separation. In that way, effects of new physics 
or ad hoc modification of spin effects component by component, can be easily included. 
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For calculating complete spin correlations, including the effects of genuine weak corrections 
in the case of the single boson mechanism of r-pair production, another solution is also 
prepared, see Section [5j It works in the case of an intermediate 7*/^ state produced in the 
annihilation of a pair of quarks. This can serve as an example for other processes which can 
be implemented in a similar manner. 

Let us stress that in the case of including complete spin effects it is not possible to attribute 
helicity states to the produced r leptons. This can be done only in an approximate way. For 
that purpose, a modified formula ([T]) can be used. The weight for each helicity configuration 
is: 

weighty , ) = - Y. hlhlRijP^Pfj, (2) 

i,j,i'j'=0 



The matrices P^'^ (spin projection operators) read 



P 



1,2 



/I 
















1/ 



As a consequence for Hell=ibl and Hel2=ibl 

/weight{+,+) = (hl + hl) (hl + hl) {Rqo + R03 + R30 + R33)\ 

weighti+, -) = (hi + hi) (hi - hi) (Poo - ^03 + ^30 - ^33) 

weighti-, +) = {hi - hi) {hi + hi) (Poo + ^03 - ^30 - ^33) 

\weight{-,-) = {hi -hi) {hi -hi) (Poo - P03 - P30 + ^33)/ 

The actual helicities can be then attributed by unweighting the above helicity weight. 

It is no omission that we are not explicit on sign conventions for the generated helicity 
variables Hell and Hel2. This depend on the particular choice of boosting routine. Our 
choice adopted here is, that for the r pair produced at the Z peak on average both Hell and 
Hel2 will be negative and Hell = Hel2. 



5 Electroweak Corrections and Refined Spin Effects 



5.1 External Calculation of the Spin Density Matrix Rij 

Our program is equipped with methods for calculating simple spin density matrices for most 
of the interesting hard processes. These methods are explained in the text of the paper, see 
Section SI In some cases, notably in the case of t^t~ produced from the annihilation of a 
pair of quarks, the standard density matrices may not be sufficient for some applications. A 
more exact solution is also available. Instead of a native Rij density matrix, an externally 
calculated one can be used. 

The solution is based on SANC library \27\ [28] for calculation of electroweak correctionj^. 
With its help the density matrix Rij for qq — )• r+r" process can be calculated as a function 

^^It may serve as an example of how other calculations featuring heavy Z' boson, for example, may be used 
in our interface. 
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of the incoming state flavour and Born level variables (Mandelstam s and scattering angle 
6). Additional two weights are also provided, which include the matrix elements squared 
and averaged over the spin. For additional weights genuine weak corrections are respectively 
switched on and off. This may be helpful for the evaluation of genuine weak corrections for 
states of large s, significantly above the Z peak, where they become sizable. See eg. refs. 
[201 EI]. 

For better modularity of the interface and to speed up execution of the program, pretabulation 
is used. At first, a dedicated module has to be invoked, as will be explained later. In such 
dedicated runs, Rij is calculated and stored in a lattice of (s and cos 9) points. 

Later, in the actual execution of our interface, these pretabulated values of Rij are interpo- 
lated to the actual phase space point. For this purpose, the standard bilinear interpolation 
algorithm is used. Additionally, in order to avoid numerical errors, for cos 9 values near -1 
and 1 we're using the linear extrapolation algorithm. 

Pretabulation is prepared for 3 domains of s: around the Z peak, close to the WW pair 
production threshold and over a broad energy range. The actual choice for pretabulation 
zones is 85 GeV< ^/s < 110 GeV, 160 GeV< ^/s < 220 GeVEl, 6 GeV< ^/s < 17 TeV. For s 
below 36 GeV^ the analytic form taken from ref. [29] is used. It features all spin and mass 
effects, but electroweak corrections, and even Z exchange, are not taken into account. This 
is reasonable for s < 36 GeV^ (up to, say, 100 GeV^). 

The advantage of this solution is that results of SAMC library calculation can be modified 
by the user before it is loaded into our interface without intervention into the code of the 
interface itself. 



5.2 Conventions of Frames: KORALB, SANC and TAUOLA Inter- 
face 

It is not essential for TAUOLA Interface and the segment calculating electroweak corrections 
to follow exactly the same conventions for spin quantization. In TAUOLA Interface we follow 
the frame orientation exactly as in paper [30|. The adopted frame orientation is shown in 



Fig. 2(a) In SANC, the orientation of axes is different, see Fig. 2(b) In the case of our interface, 
the beam momenta are laid along the z axis. The anti-particle beam is parallel, particle beam 
is antiparallel. The y component of the t~ is always positive. The 9 angle to be used for 
calculation of the density matrix is between the directions of the antiparticle beam and the 
r+. In the case of the SANC module, the r momenta p^+^p^- are laid on the xz plane. The 
xz plane is the reaction plane: a beam of particles (quarks or leptons) is parallel to the z 
axis. The x component of p^- is always negative. The y and y axes of the r"*" and t~ spin 
frames correspondingly have opposite direction to each other. The y axis is parallel to the y 
axis of the hard process frame. Appropriate rotations and other convention adjustments are 
performed by the program in preparation of the Rij tables: SANCtable . cxx. 



In the case when the apphcation featuring Z' is used this pretabulation zone should be replaced, for 
example by Mz> - z' < -/s < Mz' + 2>V z' ■ 
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(a) KORALB-like orientation (b) SANC module orientation 

Figure 2: The relative orientation of reference frames for the spin states of r^, and for 
hard processes as used in our interface (Fig. (a)) and in SANC module (Fig. (b)) are shown. 
In Fig (a) the axes x (not shown explicitly), x' and x" are parallel to each other and point 
behind the picture, axis z is parallel to the direction of the anti-particle beam. In Fig (b) the 
axis z is parallel to the direction of the particle beam, the axis y' points behind the picture. 
Axes y (not shown explicitly) and y" point toward the reader and are antiparallel to y'. 



5.3 Numerical Significance of Electroweak Corrections 



One may wonder whether the numerical results induced by electroweak corrections are of 
any practical purpose. They are expected to be of the order of 1% and indeed are not that 
large for the intermediate state virtuality of up to 100 GeV above the Z boson mass. The 
situation changes however significantly at higher energies. As can be seen from Figures [3] 
and m the effect may be of the order of even 50% at virtualities of several TeV. This is 
quite in agreement with the results of refs. [2H I20| . In Figures 5(a) and 5(b) we collect 
results for r polarization calculated at cos 9 = —0.2. Again, the effects are small up to the 
energy scale of about 500 GeV. At larger scales corrections become sizable. The electroweak 
corrections should be therefore considered in studies aiming for new physics phenomena such 
as Z' — r+T~ decays. 



6 Tests of Spin Correlations and Numerical Results 

There are two purposes of the presented results in this section. On one hand these results 
complement the technical tests described in Appendix IB. 21 with the ones oriented toward 
a particular hard processes. The technical tests should be repeated for every new program 
installation or configuration. On the other hand, results of the present section are of potential 
physics interest as well. They illustrate the dominant spin effects on idealized distributions 
for LHC measurements. 

Tests presented here were conducted using MC-TESTER[141 [15]. MC-TESTER allows semi- 
automated comparisons of invariant mass distributions of each sub-group of eg. r or Z 
stable decay products. The results of these tests were also compared to the results obtained 
with the FORTRAN Interface (which has been well validated by comparison with analytical 
and numerical calculations for r pair productioiJ^ . 



This represents tests of interface. In all cases r decays are generated with the help of TAUOLA FORTRAN. 
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Figure 3: The integrated cross section of r pair production from up quarks calculated with 
and without NLO EW corrections (red and blue lines) is shown in the left hand side plot. The 
ratio of the two distributions is given on the right hand plot. We are using the alpha scheme for 
electroweak corrections. That is why light fermion loops contribute to the difference between 
the two lines. The differences between the alpha scheme Born predictions and expressions 
used in the host program must be understood before the correcting weight (see Appendix 
\Cl\i is used. 



In addition to this, we created custom MC-TESTER macros for plotting other spin sensitive 
quantities and compared these to published results. Numerical results are presented later in 
the section, see Figs. [8(a)| [8(b)] and [9(a)j [9(b)| 



6.1 Z/7^r+r- 

The longitudinal spin effects for Z decay into r's was tested by restricting the r decay mode 



to —7- tt^Vt and examining the invariant mass of the vr+vr" pair, M^^+j^- (see Fig. 6(a) ) 
and the vr energy distribution in the rest frame of the Z (see Fig. |6(b)[ ). The effect of Z 
polarization on these distributions was studied in [31] and we obtained consistent results with 
the new C-|— |- implementation of the TAUOLA Interface. 

For a review of physics oriented tests of r decays themselves, and projects for future improvements based on 
low energy e'^e~ data, see ref. [3]- 
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Figure 4: The integrated cross section of r pair production from down quarks calculated 
with and without NLO EW corrections (red and blue lines) is shown in the left hand side 
plot. The ratio of the two distributions is given on the right hand plot. We are using the 
alpha scheme for electroweak corrections. That is why light fermion loops contribute to the 
difference between the two lines. The differences between the alpha scheme Born predictions 
and expressions used in host program must be understood before the correcting weight (see 
Appendix IC.7P is used. 



6.2 H^A^^T+r 



As was done for Z decay in Section [6. H longitudinal spin effects for Higgs decay into r's was 
tested using M^^+t^- (Fig. 7(a) ) and the vr energy distribution in the rest frame of the 
(see Fig. |7(b)[ ), which was flat as expected. 



Let us now turn to transverse spin correlations. In Fig. 8(a) the benchmark histogram as 
produced by our FORTRAN Interface and given in Fig. 3 of reference [32] is reproducecf^. It 



V. 



features acollinearity of the vr'^, vr^ pair in the Higgs boson rest frame, both r's decay to tt 
For the same decay set up, Fig. |8(b)| features acoplanarity of the planes built respectively 
on decay products of and r~. The spin effect is indeed large. However, it requires use 
of unobservable neutrino momenta. It is difficult or even impossible to achieve sufficient 
experimental precision in reconstruction of the reaction frame necessary for this observable. 
Also, the first observable presented on Fig. |8(a) suffers from the same limitation. 



The two other tests. Figures 9(a) and |9(b)" present distribution of acoplanarity angle for the 



two planes built respectively on the momenta of vr+vr and vr^vr , the decay products of p 
and All in the rest frame of the /o-pair. It is directly based on measurable quantities. 
The originate respectively from — t- vp^ decays. There is no need for Higgs rest frame 



In the plot the case of non zero scalar-pseudoscalar mixing was chosen. This is the origin of the difference 
with ref. [32] ■ 
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(a) Up quarks (b) Down quarks 



Figure 5: Polarization for r leptons produced from up quarks (Fig. (a)) and down quarks 
(Fig. (b)) at cosO = —0.2. The red line is with electroweak corrections, the black is Standard 
Born as is default in the interface. The blue line is Born according to alpha scheme. The 
main purpose of these results is a technical test of the software installation. Note however 
the inadequateness of the alpha scheme Born, which is significantly different from the other 
two results even at relatively low energies. The small bump on the red line on Fig. (a) is due 
to the WW threshold. It is insignificant for positive cos 9. 

I Comparison of Mass(1 ) of pi- pi+ in channel ZO => pi- pit nu_tau- nu_tau | SJ)p | Cpmparison of Mass(2) ol pi- nu_lau- niijau In channel ZQ pi- pi+ nu_lau~ nujau | gDp 




Figure 6: Longitudinal spin observables for the Z boson (e^e^ — )• Z at 500 GeV). Distribu- 
tions are shown for spin effects switched on (red), spin effects switched off (green), and their 
ratio (black). 



reconstruction in this case. Events are divided into two categories. If the energy difference 
between charged and neutral pions coming from the two r's are of the same sign, they 
contribute to Fig. 9(a) otherwise they contribute to Fig. |9(b)[ For details of the definition 
and for more numerical results obtained with the FORTRAN Interface, see 



23 



Comparison of Mass(1} of pi- pit in channel HO I => pi- pit nu lau- nu lau | SDP | Compatison of Mas5(a| ol pi- nu_iflu- nu_iau In channel H0_1 => pi- pit nu_iau- nu_tflu | ^Qp 




Figure 7: Longitudinal spin observables for the H boson for — t- tt^Vt- Distributions are 
shown for spin effects switched on (red), spin effects switched off (green), and their ratio 
(black). 
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(a) -k'^tt acoUinearity distribution (~ vr)) 




(b) TT^TT acoplanarity distribution 



Figure 8: Transverse spin observables for the Higgs boson for — )• tt^Vt- Distributions 
are shown for scalar Higgs (red), scalar-pseudoscalar Higgs with mixing angle ^. For the 
definition of angles see Section 16.21 





(a) acoplanarity distribution (1/13/2 > 0) 



(b) acoplanarity distribution (j/i?/2 < 0) 



Figure 9: Transverse spin observables for the Higgs boson for — )• tt^tt^Ut-. Distributions 
are shown for scalar Higgs (red), scalar-pseudoscalar Higgs with mixing angle j (green). For 
the definition of angles see Section 16.21 



6.3 



and 



For the simplest decay mode — >• vr^z/,-, as was already discussed in ref. [3T], the pion energy 
spectrum should be softer in the case of decays and harder in the case of charged Higgs 
decay. This is indeed reproduced in Figs. 10(a) and |10(b")] and the spectra are reversed for 
the two cases. 
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Figure 10: Pion energy spectrum in the rest frame of W (left hand side) and (right-hand 
side). Spin effects included (red line) and neglected (green line) are plotted. The variable 



1 — 2j^^ or 1 — 2-^^ is used respectively. 



7 Outlook 



Let us summarise briefly the next steps which are planned for the work on TAUOLA Universal 
Interface. Further extension of our work will be focused on generating spin states in the 
production processes from quantities which can be experimentally measured for real data 
events. Discussion of systematic error for such reconstructed spin states will require discussion 
of QCD corrections. 

At present, our interface is designed to work with the HepMC event record. However, following 
the design we tested in MC-TESTER |14^ [T5] it will be rather easy to adapt to any other event 
structure, by writing the appropriate event record interface. 

TAUOLA Universal Interface as well as TAUOLA itself are expected to remain framework-like 
code where the user is supposed to modify some of the parts according to her/his particular 
purposes. 

The segment of code for analyzing the hard process and generating spin states is now becoming 
a significant component of the project and already exceeds by far the category of peripheric 
methods related to the TAUOLA Interface. In the future it should be moved to a separate 
class. 

We expect that in the next few years better parametrization of hadronic form-factors based 
on r data from the Belle and BaBar collaborations and refined models of decays will be- 
come available. Then the directory /tauola-f ortran will be replaced by the new version 
incorporating those achievements. 
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A Appendix: Interface to TAUOLA FORTRAN 



From the point of view of a C++ interface, the r decay hbrary should be seen as a black-box. 
The code of the library is stored in the directory tauola-f ortran and is identical to the one 
stored in the directory TAUOLA, documented in ref. |9]. Minor adaptations which have been 
made affect platform-dependent files only. In the future, we expect this part of the code to 
be replaced with the new version based on work proposed in [3j. This is one of the main 
reasons why we still keep the code in FORTRAN. 

This section is addressed to developers of the interface, and special users interested in versions 
of the TAUOLA initialization other than default one, cleo. For this purpose we describe the 
common blocks and routines which allow communication between TAUOLA and TAUOLA C++ 
Interface. Even though they are explained already in refs [6] [TJ El [9] ■ The repetition here 
is convenient for easier explanation of user configuration discussed in Appendix [Cj 

A.l Common Blocks 

IDFC r PDG id 

IDFF int PDG id of the 'first' r must be 15 or -15 

TAUPOS Position of r's in the event record common block 

NPA int first r position 
NPB int second r position 

PARMAS Particles masses and widths 

AMTAU float mass of r 
AMNUTA float mass of i^r 
AMEL float mass of e 
AMNUEL float mass of i^e 
AMMU float mass of /i 
AMNUMU float mass of 
AMPIZ float mass of 7r° 
AMPI float mass of tt^ 

AMRO float mass of p (As used in some but not all decay channels for parametrization 
of hadronic currents. The same is true for all other unstable intermediate state 
particles and resonances.) 

GAMRO float width of p 

AMAl float mass of oi 

GAMAl float width of oi 

AMK float mass of 

AMKZ float mass of 

AMKST float mass of K* 

GAMKST float width of K* 
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JAKI control variables for the decay channels 

JAKl int chosen decay channel for the first r, if set to a random choice will be done 

accordingly to predefined branching ratios 

JAK2 int chosen decay channel for the second r, if set to a random choice will be 
done accordingly to predefined branching ratios 

JAKP int used in some FORTRAN applications only 

JAKM int used in some FORTRAN applications only 

KTOM int used in some FORTRAN applications only 

TAURAD variables for QED radiative corrections in leptonic r decay channels 
ITDKRC float 1/0 radiative correction on/off 

XKODEC float minimal energy of photon to be generated (with respect to maximum 
possible value). 

TAUBRA Variables for composition of r decay channels. 

GAMPRT[30] float (non negative) one dimensional matrix of r decay branching 
ratios used if JAK1=0 or JAK2=0. Can be changed by the user at any time of 
generation. GAMPRT does not need to sum up to 1. Default of any entry can be 
changed by invoking method Tauola: : setTauBrC int i, double br). 

JLIST[30] integer one dimensional table, to be left unchanged. It is basically a 

FORTRAN emulation of a table of pointers. 

NCHAN integer number of r decay channels which can be used, all higher than 
NCHAN values of GAMPRT are dummy. 

TAUKLE Further variables for composition of some of the r decay sub-channels 

BRAl float relative branching ratio between — t- 7r"'"7r"'"7r~ and ag — > Tr^Tr^Tr"*" 
BRKO float relative branching ratio of Kq decay 
BRKOB float relative branching ratio of Kq decay 
BRKS float relative branching ratio of K* decay 

A. 2 Routines 

INIETC Initialize content of JAKI and TAURAD common blocks. 
Return type: void 
Parameters: none 

INIMAS Initializes masses stored in common block PARMAS 

Return type: void 
Parameters: none 

INIPHX Initializes parameters of QED, common block QEDPRM. 
Return type: void 
Parameters: none 
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INITDK Initializes kinematical information on r decay channels: branching fractions to be 
used for JAK1,JAK2=0, masses and flavours of scalars for each decay channel, names 
of the decay channels. It is well documented in the FORTRAN version of the program. 
This routine should be left unchanged. Defaults of the GAMPRT matrix residing in 
the common block TAUBRA, can be changed before any consecutive execution of the 
routine DEKAY. 
Return type: void 
Parameters: none 

INIPHY Initializes parameters of QED, common block QEDPRM, 
Return type: void 
Parameters: 

1. float P/=3.1415... 

2. float ALFINV =l/aQED 

3. float ALFPI =aQED/T^ 

4. float XKO = dummy at present 

DEXAY Generates decay of a polarized r. DEKAY is more powerful for spin effects and 
should be used in preference to this. 
Return type: void 
Parameters: 

1. int state parameter defining the choice between r+ and t~ . If set to 1, a decay of 
r with ID=IDFF will be performed, otherwise it will be for ID=-IDFF. In both 
cases FILHEP will be invoked to store the appropriate decay products in the event 
record. 

2. double pol[4] input r polarization vector. 

DEKAY Generates an unpolarized r decay 
Return type: void 
Parameters: 

1. int state parameter defining choice between and t~ . If set to 1, decay of a 
r with ID=IDFF will be performed, for 2 it will be with ID=-IDFF. For 11 and 
12 FILHEP will be invoked to store the appropriate decay products in the event 
record. 

2. double [4] returns vector H see Section H] 
A. 2.1 C++ Routines Called by TAUOLA FORTRAN 

void filhep_ (int n, int status, int pdg_id, int mother_first, int mother_last, int 
daughter _first, int daughter _last, float p4[4], float p_inv_mass, bool pho- 
tos_flag) puts the particle into the event record. A long list of its parameters (variables 
named in HEPEVT style), is given below: 

1. n Index of the particle 

2. status Status code of the particle 

3. pdg-id PDG id of the particle 

4. mother_first Index to the particles first mother 
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5. motherJast Index to the particles last mother 

6. daughter-first Index to the particles first daughter 

7. daughterJast Index to the particles last daughter 

8. p4[4] 4- momentum, the last component is energy 

9. p_inv_mass Mass of the particle 

10. photos-flag Should PHOTOS be called for this particle 

void tralo4_ (float * kto, float p[4], float q[4], float * ams); FORTRAN routine which is used 
to boost the four vector p[4] from first/second r's (kto=l/2) rest frame to laboratory 
frame q[4]. ams denotes a four vector mass or virtuality. 

float amas4_ (float*); returns the mass of the argument four vector. 

void bostr3_ (float*, float*, float*); This routine performs boosting (with boost parameter 
given by the first argument) of a four vector (second argument) into a four vector (third 
argument). 



B Appendix: User Guide 
B.l Installation 

The main interface library requires that HepMC [lOj (version 2.04 or later) has been installed 
and its location has been provided during the configuration step. This is sufficient to compile 
the interface and to run the simple, standalone example. 

However, in order to run more advanced examples located in the /examples directory, it is 
required to install also: 

• ROOT [M] version 5.18 or later 

• PYTHIA 8.1 [16j or later. PYTHIA 8.1 must be compiled with HepMC 2.xx so that the 
PYTHIA library hepmcinterf ace exists. 

• MC-TESTER [TH [Tg] version 1.24 or later. Do not forget to type make libHepMCEvent 
after compilation of MC-TESTER is done. 

In order to compile the TAUOLA C++ Interface: 

• Execute ./configure with the additional command line options: 

— with-HepMC=<path> provides the path to the HepMC installation directory. One 
can also set the HEPMCLOCATION variable instead of using this directive. This path is 
required for the interface to compile. 

— pref ix=<path> provides the installation path. The include and lib directories 
will be copied there if make install is executed later. If none has been provided, the 
default directory for installation is /usr/local. 
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Execute make 



• Optionally, execute make install to copy files to the directory provided during con- 
figuration. 



After compiling the TAUOLA/tauola-f ortran part, the TAUOLA C++ interface will be com- 
piled and the /lib and / include directories will contain the appropriate libraries and include 
files. 

In order to compile the examples, enter the /examples directory and: 



• Compile TAUOLA C++ interface 

• Execute . /configure to determine which examples can be compiled. Additional paths 
can be provided as command line options: 

— with-Pythia8=<path> provides the path to the PythiaS installation directory. 
One can set the PYTHIALOCATIDN variable instead of using this directive. This path is 
required for all additional examples and tests. 

— with-MC-Tester=<path> provides the path to the MC-TESTER installation di- 
rectory (the libHepMCEvent must be compiled as well, see [15] for more details). One 
can set the MCTESTERLOCATION variable instead of using this directive. This path is re- 
quired for all additional examples and tests. This option implies that ROOT has already 
been installed (since it is required by MC-TESTER). The ROOT directory bin should be 
listed in variable PATH and ROOT hbraries in LD_LIBRARY_PATH. 

• execute make 



If neither PythiaS nor MC-TESTER are present, only the simple example will be provided. The 
/examples directory will contain the compiled example files. 



B.2 Elementary Tests 

The most basic test which should be performed is verification that the interface is installed 
correctly, that all r leptons are indeed decayed by the program and that energy momentum 
conservation is preserved. TAUOLA has its own database of parameters and as a consequence 
the r lepton mass may differ between the program performing a r's production and TAUOLA 
performing its decay. This leads to the sum of r decay product momenta not exactly matching 
the r's momentum. Although this effect may seem negligible, it may break numerical stability 
of programs like PHOTOS if they are applied later. 

Once correct execution of the basic program steps have been confirmed, ie. r leptons are 
decayed, energy momentum is conserved and there are no double decay occurrences in the 
event tree, step one of the program installation tests is completecf^. 

In principle, these tests have to be performed for any new hard process and after any new in- 
stallation. This is to ensure that information is passed from the event record to the interface 



We have performed such tests for all choices of the HepMC event record obtained from PYTHIA 8 . 1 pro- 
cesses and listed later in the paper. Further options for initializations (parton shower hadronization or QED 
bremsstrahlung on/off etc.) were studied. This installation step was a necessary one of program development 
as well. 
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correctly and that physics information is fihed into HepMC in expected manner. Misinterpreta- 
tion of the event record content may result in faulty generation by TAUOLA. For example spin 
correlations may be missing or badly represented, or some r leptons may remain undecayed. 



B.3 Executing Examples 

Once elementary tests are completed one can turn to the more advanced ones. The purpose 
is not only to validate the installation but to demonstrate how the interface can be used and 
how spin affects some distributions. 

The examples can be run by executing the appropriate . exe file in the / examples directory. In 
order to run some more specific tests for spin effects and decays of the following intermediate 
states: Z, W, H, H^, the main programs residing in subdirectories of the same name placed 
in the /examples/testing directory should be executed. For tests of all r decay modes 
directory /examples/testing/tau is prepared. In all cases the following actions have to be 
performed: 

• Compile TAUDLA C++ Interface as well as the examples. 

• Check that the appropriate system variables are set: normally set by the script 
/configure .paths . sh (the configuration step mentions this script). 

• Enter the /examples/testing directory. Modify test.inc if needed. 

• enter the chosen directory and execute make. 

The appropriate .root files as well as .pdf files generated by MC-TESTER will be created inside 
the chosen directory. One can execute 'make clobber' to clean the directory. One can also 
execute 'make' inside the /examples/testing directory to run all available tests one after 
another. New source code changes can easily be validated in this way. Tests are run using 
examples/taumain_pythia_example . exe and booklets will be produced with comparisons to 
the benchmark files. 

A set of benchmark MC-TESTER root files are packed with the interface distribution in the 
subdirectories of examples/testing/. They can be used as examples to start new work or 
simply to construct comparison plots to validate new versions or new installations of TAUOLA 
Interface. 

In Appendix [C] possible modifications to the examples settings are discussed. This may be 
interesting as an initial step for users physics studies. Numerical results of some of these tests 
are collected in Section [6] and can be thus reproduced by the user. 

B.3.1 Monitoring r Decay Channels 

It is important to check, if the r decays themselves, are generated correctly on the user 
platform. For that purpose, our last demo (directory /examples/testing/tau) is prepared. 
If the test is activated, the user performs a standard MC-TESTER comparison of his program 
execution with the pre-generated one (of 10 million events). In this case all r decay modes 
are activated and MC-TESTER is simply analyzing r decays themselves. 
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B.4 Library Linking 



In order to link the libraries to the user's project, both the static libraries and shared objects 
are constructed. To use TAUOLA FORTRAN and TAUOLA Interface in an external project 
additional compilation directives are required. For the static libraries: 

• add -I<TauolaLocation>/include at the compilation step, 

• add <TauolaLocation>/lib/libTauolaCxxInterf ace . a and 
<TauolaLocation>/lib/libTauolaFortran.a at the linking step. 

For the shared objects: 

• add -I<TauolaLocation>/include at the compilation step, 

• add -L<TauolaLocation>/lib along with -ITauolaCxxInterf ace -ITauolaFortran 

at the linking step. 

• TAUOLA libraries must be provided for the executable; eg. with the help of LD .LIBRARY _PATH 



The <TauolaLocation> denotes the path to TAUOLA installation directory. 



B.5 Known Issues 

We list here difficulties we've encountered during the testing phase and during installation 
for particular configurations. 

The first problem occurs if a user incorrectly configures the units of PYTHIA to be different 
from the units in HepMC. (for example: if PYTHIA produces output in MeV, while HepMC 
interprets input as being in GeV). In this case, the built-in routines of TAUOLA Interface 
will treat the input as being in GeV and will adapt its output to those units as well. If this 
kind of situation occurs (the user will be notified by many warnings of four- vector momentum 
not being conserved), one can force HepMC to use MeV units just before filling it with the 
Pythia event record data. The HepMC event will be automatically converted to GeV when 
TAUOLA Interface is called. 

Another example of a known compatibility issue arose because of a difference between the as- 
sumed default HepMC version 2.05 and version 2.03 (currently used, for example, in Athene!^ . 
In this case, the script platf orm/to-HepMC-2 . 03. sh will be automatically invoked dur- 
ing the configuration step. However, in version 2.03 methods for unit conversion are ab- 
sent, therefore GeV and mm will be expected for input and used for output. The method 
Tauola: :setUnits(. . .), described in Appendix IC.lH becomes dummy. 

At present, modification to our C++ Interface has to be introduced eg. for use in the Athena 
system of the ATLAS collaboration software. This is to allow for backwards compatibility 
with older versions of HepMC and to prevent name clashes with the old TAUOLA FORTRAN 
Interface in environments where both interfaces are loaded concurrently. On the other 
hand, there is no problem with the library /lib/libTauolaFortran. a of the main part of 

Software framework of the ATLAS collaboration. 
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the TAUOLA FORTRAN code itself. The version used by Athena can be loaded instead of ours. 
In Athena, the binp variant of the cleo initialization is used for TAUOLA; in this variant, for 
the 47r decay modes of r's, parametrization based on Novosibirsk data is used |35j . 

All necessary changes for our C++ TAUOLA Interface can be introduced with use of the script 
platf orm/to-Athena. sh. It can be invoked by executing the make athena command in the 
main directory. Recompilation of the interface must then be performed. 



C Appendix: User Configuration 

In this section we give a description of how the user can configure TAUOLA FORTRAN and 
the TAUOLA Interface. All configuration is done via the static class Tauola. Below is the 
complete list of user configurable parameters and basic information on their meaning. 



C.l Spin Correlation 

By default, all spin correlations are turned on. However one may be interested to partially 
or completely switch off their effects for the sake of numerical experiments which validate 
whether a measurement will be sensitive to certain spin correlation components. This tech- 
nique may be useful to evaluate the significance of spin correlations for signal/background 
separation as well. 

Several partial treatments of spin correlations are possible. In general, the most complete 
intervention is to simply rewrite the matrix Rij for the particular channel. The following 
methods are nonetheless provided: 

• Tauola: : spin_correlation. setAlKbool flag) 

Turns all spin correlation computations on or off depending on the flag, which can be 
either true or false. Note: this should be called after Tauola: :initialise(). 

• Tauola: :spin_correlation.HIGGS=flag 

Turns particular spin correlation computation on or off for a given r parent depend- 
ing on the flag which can be either true or false. Implementation of this switch is 
provided for: GAMMA, ZO, HIGGS, HIGGS_H, HIGGS_A, HIGGS_PLUS, 
HIGGS_MINUS, W_PLUS, W_MINUS. The keywords denotes the r parent. 

Example: 

Tauola: : spin_correlation. setAll (false) ; 
Tauola: : spin_correlation.HIGGS=true; 

Turns all spin correlations off, except HIGGS. 

Finally one can replace density matrix following description given in Appendix ID. 31 also in 
this case one does not need to recompile of the code. 
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C.2 Decay Mode Selection 



By default, all r decay modes will be generated according to predefined branching fractions. 
Methods to modify the default values are provided: 

• Tauola: : setSameParticleDecayMode (int mode) 

Set the decay mode of the r with the same PGD code as set in 

Tauola: :setDecayingParticle() (by default this sets the decay mode of r~). 

• Tauola: : setOppositeParticleDecayMode (int mode) 

Set decay mode of the r with the opposite PGD code as set in 

Tauola: :setDecayingParticle() (by default this sets the decay mode of r"*"). 

Example: 

Tauola: : setSameParticleDecayMode (Tauola: :Pion]yiode) ; 
Tauola: : setOppositeParticleDecayMode (4) ; 

Forces only the modes t~ — >■ Tr~i'r O'^d r"^ — > p'^i'rip^ ir'^ir^) to be generated 

• Tauola: : setTauBr( int mode, double br) 

Change the r branching ratio for channel mode from default to br. Note: this should 

be called after Tauola: :initialise(). 

Example: 

Tauola: :setTauBr (3, 2.5); 

Sets rate for channel — )■ Tr^Ur to 2.5. All channel rates may not sum to unity, 
normalization will be perfrmed anyway. 

• The int mode enumerators which are arguments of setOppositeParticleDecayMode, 
SetSameParticleDecayMode, setTauBr have the following meaning: 

- - Tauola: :A11 - All modes switched on 

- 1 - Tauola: : ElectronMode - — t- e^UrVe 

- 2 - Tauola: :MuonMode - — t- ix^VT-f^ 

- 3 - Tauola: :PionMode - — )■ tt^u 

- 4 - Tauola: :RhoMode - ^ p^u 

- 5 - Tauola: :AlMode - ^ Afv 

- 6 - Tauola: :KMode - K^v 

- 7 - Tauola: :KStarMode - ^ K*^v 

- 9 - r± ^ 37r°7r±i/ 

- 10 - r=^ ^ 2iT^'K^2-iT^u 

- 11 - r± ^ ^'K^2iT^v 

- 12 - T± ^ 37r±27rT7r0z/ 

- 13 - T± ^ 27r±7rT37r0z/ 

- 14 - ^ K^K^T^^v 

- 15 - T± ^ K^K^-K^u 

- 16 - ^ K^K^TT^v 
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- 17 - r± ^ 2tt^K^v 

- 18 - r± ^ -K^-K^K^v 

- 19 - r± ^ -K^-K^K^v 

- 20 - r± ^ r/7r=^7r°i/ 

- 21 - — ;> 7r='=7r°7i/ 

- 22 - r± ^ K^K^v 

• Tauola: : setTaukle (double bral, double brkO, double brkOb, double brks) 

Change the r sub channels branching ratio between (i) ao — ?• vr+vr+vr^ and oq — )• 7r''7r'^7r+ 
(ii) subchannels of Kq (iii) subchannels of Kq and (iv) subchannels of K* . Note: this 
should be called after Tauola: :initialise(). 

Example: 

Tauola: : setTaukle (0.5, 0.5, 0.5, 0.6667); 

Set the parameters to their default values 



C.3 Decaying Particle 

The following method is prepared to impose the sign for the 'first r', that is to reverse signs 
of SameParticle and OppositeParticle r: 



• Tauola: : setDecayingParticle(int pdg_id) 

Set the PDG id of the particle which TAUOLA should decay as 'first r'. Both particles 
with pdgJd and -l*pdg_id will be decayed. Default is 15, one may want to use -15 for 
special applications. 



Example: 

Tauola: : setDecayingParticle(-15) ; 
Set SameParticle r to he 



C.4 Radiative Corrections 

The user may want to configure parameters used in the generation of QED corrections in the 
leptonic decay channels of rs. For that purpose the following methods are provided: 

• Tauola: : setRadiation(bool switch) 

Radiative corrections for leptonic r decays may be switched on or off by setting the 
switch to true or false respectively. By default this is 

'^^Only in the case of leptonic r decays can radiative corrections be generated in TAUOLA [7]. The algorithm 
relies on the first order complete matrix element and no exponentiation is available. If the multiple photon 
option is requested or if radiative corrections for other decay channels are needed PHOTDS Monte Carlo can be 
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• Tauola: : setRadiationCutOff (double cut_off) 

Set the cut-off for radiative corrections of r decays. The default of 0.01 means that 
only photon of energy (in its rest frame) up to 0.01 of half of the decaying particle mass 
will be explicitly generated. 

Example: 

Tauola: : setRadiation(f alse) ; 

Switch radiative corrections off in r decays 



C.5 Decay of Final State Scalars 

In some cases a user may want TAUOLA to decay short living scalar particles produced in 
decays, rather than invoking a host generator for the post processing step. For that purpose 
a special algorithm is prepared, even though high precision is then not assured. This might 
not be a problem if the algorithm is used for r decays only where events with such decays 
are rather rare: 

• Tauola: : setEtaKOsPi (int a, int b, int c) 

The three parameters a, b and c switch on or off the decay of rj, Kg and respectively. 
A value of 1 is on and is off. 

Example: 

Tauola: : setEtaKOsPi (1 , 0, 1) ; 

In event branch starting from t, rj and decay, but remains undecayed. 



C.6 Scalar-Pseudoscalar Higgs 

Users may wish to study spin correlations in processes involving scalar, pseudoscalar or mixed 
scalar-pseduoscalar decays into r's. All options are supported by this interface. The spin 
density matrix will be calculated correctly for scalar Higgs (assumed PDG id of 25) and 
for pseudoscalar Higgs (assumed PDG id of 36) without any additional user configuration. 
For other cases, such as a mixed scalar-pseduoscalar Higgs or the decay of non-Higgs scalar 
particles, the following methods are provided: 

• Tauola: : setHiggsScalarPseudoscalarMixingPDG (int pdg_code) 

The PDG Monte-Carlo code of the Higgs which should be treated by the interface as a 
scalar-pseudosclar mix. The default value is PDG id 35. Please note that if ;)dg_code 
is set to the value of an existing spin case (eg. 25, the regular scalar Higgs) the scalar- 
pseudoscalar case will be assumed. 

• Tauola: : setHiggsScalarPseudoscalarMixingAngle (double angle) 

The scalar-pseudoscalar mixing angle, ie. cj) in the coupling: f(cos(0) -|- isin{<j))^5)T. 
By default = f . 

used instead [13) . In [36] it was shown, that the numerical efTects due to the parts not included in PHOTOS of 
the first order matrix element is numerically more significant than multiple photon effects. This conclusion is 
based on our standard numerical tests and will not necessarily be the case for other applications. 
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Example: 

Tauola: : setHiggsScalarPseudoscalarMixingPDG(24) ; 

Tauola: : setHiggsScalarPseudoscalarMixingAngle (3. 1415/3.0) ; 

Spin correlations will be calculated for the Higgs boson as though it is a scalar-pseduoscalar 
with mixing angle of ^ 



C.7 Helicity States and Electroweak Correcting Weight 

Independent of the generation process, the information on helicities of t+ and can be 
returnecf^ with the help of accessors: 

• int Tauola: : getHelPlus () 

• int Tauola: : getHelMinus () 

Note that these helicities are not used in the interface and carry approximate information 
only. 

The electroweak weight can be returned with the help of accessors: 

• double Tauola: :getEWwt() - for cross section with electroweak corrections included 

• double Tauola: :getEWwtO() - for cross section at born level 

These methods provide information once processing of a given event is completed. 



C.8 Use of TAUOLA decayOne method 

In Section 13.31 an algorithm to decay all r leptons present in the event record is explained. 
For that purpose decayTausO method is provided. To decay a single r lepton in a way 
independent of the event record content another, simple method is provided. Obvious ex- 
amples when it can be useful, are processes where the hard matrix element originates from 
models of new physics, and different flavours of such models are to be tested. In such cases, 
universal methods of finding spin states of the r to be decayed may not exist. Depending 
of the precision required one may need to: decay a r without taking into account its spin 
state, impose its individual spin state as input information or provide a method which can be 
used for full density matrix generation. In the last case control over Lorentz transformations 
between the r rest-frame and laboratory frame have to be available for the user. 

Fortunately for all these applications a rather simple method is sufficient. It can be used to 
generate a decay of an individual r, without information on its parents. 

• Tauola: : decayOne ( 

TauolaParticle *tau, bool undecay, double polx, double poly, double polz) 



One has to be careful because the actual sign may depend on the process and boosting routine. 
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The main routine for decaying the tau. Only the first parameter is mandatory. The 
first parameter is a pointer to the r that needs to be decayed. 

The undecay flag determines the reaction that should be taken if the r already has 
daughters. By default the flag is set to false, which means that already decayed r will 
be left unchanged. Setting this flag to true allows the interface to first undecay the r 
and replace it with a new decay. 

The last three parameters are the components of the r polarization 3-vector. In the 
case of TAUOLA decayOne, the decayed r is treated as a standalone particle, without 
considering its mothers, daughters or siblings. In case the user wants to input the 
polarization vector (at default r is treated as not polarized), the last three parameters 
have to be used. 

• Tauola: : setBoostRoutine( 

void (*boost) (TauolaParticle *tau, TauolaParticle *target) ) 
Once executed, Tauola: decayOne will use the user function instead of the default one, 
to boost r decay products from their rest frame to the lab frame. Such feature may 
be essential, in future, for use of Tauola: : decayOne as part of a user algorithm for 
generation of exact spin correlations in multi r final states. 

The single_tau_gun_example . c is provided in the directory /examples. If polarization 
polx=0, poly=0, polz=l is chosen, then the helicity state is taken: left handed t~ or right 
handed r^. If, again as given in the example Tauola: : setBoostRoutine is used with the 
proposed method, then polx=0, poly=0, polz=l will not mean helicity state, but rather 
the r spin polarization vector oriented along the z axis of the lab frame (in fact along its 
space component in the r rest-frame). Obviously spin effect chosen this way, will depend on 
the direction of the r momentum. 



C.9 Logging and Debugging 

This section describes the basic functionality of the logging and debugging tool. For details 
on its content we adress the reader to comments in the /src/utilities/Log.h header file. 

Let us present however some general scheme of the tool functioning. TAUOLA Interface 

allows filtering out some amount of data displayed diiring the program run and provides a 
basic tool for memory leak tracking. The following functions can be used from within the 
user program after including the Log.h file: 

• Log: : Summary - Displays a summary of all messages. 

• Log : : SummaryAtExit ( ) - Displays the summary at the end of a program run. 

• Log: :LogInf o(bool flag) 
Log: :LogWarning(bool flag) 
Log: :LogError(bool flag) 
Log: :LogDebug(int s, int e) 
Log: :LogAll(bool flag) 

Turns logging of info, warning, error and debug messages on and off depending on 
the flag being true or false. In the case of debug messages - the range of codes to be 
displayed must be provided. By default, only debug messages (from to 65535) are 
turned off. If the range is negative (s > e) the debug messages won't be displayed. The 
last option turns displaying all of the above messages on and off. 
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The memory leak tracking function allows checking of whether all memory allocated within 
TAUOLA Interface is properly released. However, using the debug option significantly in- 
creases the amount of time needed for each run. Its use is therefore recommended for debug- 
ging purposes only. In order to use this option modify make . inc in the main directory by 
adding the line: 

DEBUG = -D"_LOG_DEBUG_MODE_" 

Recompile the interface. Now, whenever the program is executed a table will be printed 
at the end of the run, listing all pointers that were not freed, along with the memory they 
consumed. If the interface works correctly without any memory leaks, one should get an 
empty table. 

It is possible to use this tool within the user program, however there are a few limitations. 
The debugging macro from "Log.h" can create compilation errors if one compiles it along 
with software which has its own memory management system (e.g. ROOT). To make the 
macro work within a user's program, ensure that Log.h is the last header file included in 
the main program. It is enough to compile the program with the -D"_LOG_DEBUG_MODE_" 
directive added, or #def ine _LOG_DEBUG_MODE_ placed within the program before include of 
the Log.h filfl 



C.IO Plots for Debugging and Monitoring 

This section describes the basic functionality of the plotting tool. Detailed explanations are 
given in the /src/utilities/Plot .h and /src/utilities/Plot . cxx files. 

The Plot class allows generation of data for several plots we use to monitor the interface. At 
present, r polarization, as taken from the SANG library and used by the interface (including its 
interpolation algorithm) is monitored in this way. The program generates data files during 
execution to be used later for graphic output. This code is not expected to be of a large 
interest to users. It is mainly for testing and debugging purposes, but may be of interest for 
installation tests as well. 

In order to generate input data for plotting, a few methods have been provided which can be 
accessed after adding #include "Plots. h" in the main program file: 



Plots :: setSancVariables (int flavor .double cosTheta) - sets the variables used 
by the first two tests. The first one is the flavor of incoming particle (by default it's set 
to 1), and the second is value of cos{6) (by default - 0). 

Plots: : addSancPlot (int i) - adds the i*'' test plot of the four tests prepared for 
SANG tables. All or only some of these tests can be run simultaneously. Figures O [H 



and 5(a) , 5(b) can be in particular reproduced with this method. 



Plots : : exitAf terSancPlots (bool exit) ; - if set to true, force the program to exit 
after the plots have been created. Otherwise, the program will continue normally to its 
usual end. 



The files generated with this tool can then be used to make plots with external scripts. 
For this purpose an /examples/draw. G ROOT script has been provided. If root draw.G is 

'^^Note that Log.h does not need to be included within the user program for the memory leak tracking tool 
to be used only for TAUOLA Interface. 
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executed, it checks, by name, which input data files are present. For existing data files plots 
are drawn. Since generated files contain the test data only, without much of explanation 
of their meaning, to interpret them one need to look for a description inside the Plot class 
source files. 



C. ll Other User Configuration Methods 

The following auxiliary methods are prepared. They are useful for initialization or are intro- 
duced for backward compatibility. 

• Tauola: : setUnits (Tauola: :MoinentumUnits,Tauola: : LengthUnits) 

Set output units for momentum (Tauola: :GEV / Tauola: :MEV) and decay vertex posi- 
tion (Tauola::MM / Tauola::CM). Methods are only available for HepMC 2 . 04 or higher. 

• Tauola: : setTauLifetime (0 . 08711) 

Set the mean r lepton lifetime in mm. If the user wants a vertex position to be generated 
by his own method, then the numerical value of the r lifetime should be set to 0.0 here. 

• Tauola: : setlnitialisePhy (double iniphy.param) 

Initializes some constants related to QED corrections. The variable iniphy_param is at 
present a dummy. It is prepared to be transmitted to some old style production code 
and is kept for backward compatibility. 

• Tauola: : setRandomGenerator (double (*gen)()) 

In tauola-f ortran the random number generator RANMAR is used. It is also used in 
our auxiliary methods which temporarily remain in FORTRAN. RANMAR may need to be 
replaced or a particular seed has to be chosen. It can be easily done and is explained in 
[9]. In the C-|-+ part of the code a user can simply set the pointer to the replacement 
for an internal random number generator Tauola: :RandomDouble. The generator must 
return a double from to 1. Tauola: : setRandomGenerator (NULL) will reset the 
program back to the default generator. 

D Appendix: Modifying Electroweak Corrections Mod- 
ule 

D. l SANC Unit Initialization and Input Parameters 

In this section we describe details of the SANC library initialization. Input parameters and 
constants are collected in several files located in the directory /SANC. The file s2n_declare .h 
contains a declaration of all FORTRAN variables used by the SANC NLO Library. The particle 
masses and coupling constants are initialized by the sanc_input .h header file. It is called by 
the s2n_init subroutine (see file s2n_init . f ), which initializes other parameters like particle 
mass ratios, particle charges and weak isospin projection, as well as the value of fictitious 
photon mass (thmu2) used by IR singularity regularization and soft/hard radiation separator 
(omega). Several user controlled fiags are defined: 

• iqed = 1/0 - NLO QED correction is switched on/off. Default iqed = 
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• iew = 1/0 - NLO EW correction is switched on/off. Default iew = 1 

• iborn = 0/1 - NLO correction are switched on/off; Default iborn = 

• gfscheme = 1/0 - calculation schemes: 1 - Fermi Scheme, - Alpha Scheme (default). 

These flags are used to configure table preparation by the program SANC/SANCinterf ace . cxx. 
For the SANC module structure and its project details, see refs. [271 [28], 

D.2 Structure of Files with Pretabulated Rij 

In order to generate all pretabulated files the SANC/SANCinterf ace . cxx program is used. 
When compiled along with the SANC library, SANC FORTRAN interface and modules located 
inside the SANC/modules directory, the program generates two files - tablel-l.txt and 
table2-2.txt for the quarks down and up respectively. The program is invoked with the 
command make tables from the directory SANC. The third file tablell-ll.txt represent- 
ing tabulated results for electron beams will not be generated automatically. 

The structure of each generated file consists of several blocks: 

• Initialization block 

Dimensions - NSl, NS2, NS3 and NCOS values used as dimensions of the gener- 
ated tables 

Ranges - minimum and maximum values for all three pretabulation ranges of s 

• Information block: 

Date and time of generation 
Full path of the generating program 
SANC library information block 
SANC initialization parameters list 

• Data block: 

BeginRangel statement 

tables of NSl * NCOS lines for first range 

BeginRange2 statement 

tables of NS2 * NCOS lines for second range 

BeginRangeS statement 

tables of NS3 * NCOS lines for third range 

End statement 

Lines within Data block consist of 4*4 numbers for Rij, two extra numbers for the elec- 
troweak weight and an endline character. Statements used within Data block (Begin- 
Rangel, BeginRange2, BeginRangeS, End ) are mandatory and must be present in 
exact form. They mark the beginning and end of the appropriate data set. The program 
also checks whether the data block has been read completely and verifies if variables read at 
initialization were consistent. 
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D.3 Importing SANC Tables into TAUOLA Interface 



The three files generated by the SANC module are loaded into TAUOLA Interface during 
the initialization step, if they are located in the directory of the main program. When 
Tauola: : initialize () is called, the interface searches for the appropriate files and if they 
are found - attempts to import the data. 

For a file to be loaded correctly, the dimensions of the input file must match the interface 
settings. The content and size of the information block is arbitrary. The information of this 
block will be printed only, but not used otherwise. After reading all the tables from one 
file, TAUOLA Interface checks if the end of the data block has been reached and eventually 
proceeds to the next file. 

If the dimensions do not match, the file is inconsistent with the structure (the end of the data 
block has not been reached or the file has insufficient data) - it will not be used by TAUOLA 
Interface even if the file was found. In that case the default density matrix will be used. 
TAUOLA Interface will attempt to read all of the three files, but if either one is incorrect or 
missing, only the data from those files that have been loaded correctly will be used. 

If the need arises to modify the default tables distributed with TAUOLA, the SANC folder 
includes all routines needed to generate new tables along with a Makefile with a few options, 
including: 

• make - used to recompile the library, modules and LoopTools needed for generation. 

• make clobber - might be needed to remove previous compilation. 

• make tables - used to compile the interface code and generate the tables. 

The C++ interface to the SANC library is located in the SANC/ folder. SANCinterf ace . cxx 
represents the main program with setting of options for table making. Options for table 
layout are explained in comments within the file. The interface will be recompiled every 
time make tables is used. If needed, further program options, such as initialization of 
electroweak coupling constants or particle masses for calculation of electroweak corrections 
can be modified. The SANC/SANCtable . cxx file consists of routines for actual calculation of 
table entries from spin amplitudes calculated from SANC. Changes which may be of interest 
to advanced users should be done in this file. 
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